/**
 * <h3>ISchoolService</h3>
 * <p> 学校信息管理服务接口 </p>
 *
 * <h3>功能描述</h3>
 * <p> 定义学校信息增删改查等基础业务操作，包括学校基本信息管理、校徽管理、省份城市信息等 </p>
 * <p> 支持多语言查询、学校统计信息、官方校徽管理等核心业务逻辑 </p>
 *
 * <h3>元数据</h3>
 * <ul>
 *    <li> 作者：郭强 </li>
 *    <li> 创建日期：2025年05月06日 21:15:20 </li>
 * </ul>
 *
 * <h3>其他信息</h3>
 * <ul>
 *    <li> 参考链接：<a href="https://example.com">官方网页</a></li>
 *    <li> 示例代码：{@code selectSchoolList(SchoolDTO dto)} </li>
 * </ul>
 *
 * @apiNote 接口方法需保证事务一致性与线程安全；支持中英文双语查询
 * @implSpec 继承自 {@link IService<SchoolDTO>}，扩展了按条件查询、按ID获取等方法
 * @since 1.0.0
 */

package com.dnndo.system.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.dnndo.system.domain.School;
import com.dnndo.system.domain.dto.*;
import com.dnndo.system.domain.vo.ApiSchoolEnVO;
import com.dnndo.system.domain.vo.ApiSchoolZhVO;
import com.dnndo.system.domain.vo.SchoolRelatedInfoVO;

import java.util.List;

/**
 * 学校服务接口
 * 
 * @see com.dnndo.system.domain.School
 * @see com.dnndo.system.domain.dto.SchoolDTO
 * @see com.dnndo.system.service.impl.SchoolServiceImpl
 */
public interface ISchoolService extends IService<SchoolDTO> {

    /**
     * 根据条件分页查询学校列表
     *
     * @param dto 学校查询条件封装对象，包含学校名称、类型、省份等过滤条件
     * @return List<School> 符合条件的学校信息列表
     * @see com.dnndo.system.domain.dto.SchoolDTO
     * @see com.dnndo.system.domain.School
     */
    List<School> selectSchoolList(SchoolDTO dto);

    List<School> selectSchoolNameList(SchoolDTO dto);

    /**
     * 根据条件分页查询已收录学校logo列表
     *
     * @param dto 学校查询条件封装对象，包含学校名称、类型、省份等过滤条件
     * @return List<School> 符合条件的学校信息列表
     * @see com.dnndo.system.domain.dto.SchoolDTO
     * @see com.dnndo.system.domain.School
     */
    List<School> selectSchoolLogoList(SchoolDTO dto);

    /**
     * 根据学校ID获取详细信息
     *
     * @param schoolId 学校唯一标识符
     * @return SchoolDTO 包含学校详细信息的数据对象
     * @see com.dnndo.system.domain.dto.SchoolDTO
     */
    SchoolDTO selectSchoolListById(Long schoolId);

    /**
     * 修改已有学校信息
     *
     * @param schoolDTO 包含更新字段的学校数据对象
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.SchoolDTO
     */
    int updateSchoolById(SchoolDTO schoolDTO);

    /**
     * 新增学校信息
     *
     * @param schoolDTO 包含新增字段的学校数据对象
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.SchoolDTO
     */
    int insertSchool(SchoolDTO schoolDTO);

    /**
     * 删除指定ID的学校信息
     *
     * @param schoolId 要删除的学校唯一标识符
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.SchoolDTO
     */
    int deleteSchoolById(Integer schoolId);

    /**
     * 下架指定ID的学校信息
     *
     * @param schoolId 要下架的学校唯一标识符
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.SchoolDTO
     */
    int downSchoolById(Integer schoolId);


    /**
     * 获取学校相关信息
     *
     * @param language 语言类型（zh/en）
     * @return SchoolRelatedInfoVO 学校相关信息
     * @see com.dnndo.system.domain.vo.SchoolRelatedInfoVO
     */
    SchoolRelatedInfoVO getSchoolRelatedInfo(String language);

    /**
     * 获取省份城市列表
     *
     * @param language 语言类型（zh/en）
     * @return List<ProvinceDTO> 省份城市列表
     * @see com.dnndo.system.domain.dto.ProvinceDTO
     */
    List<ProvinceDTO> getProvinceCityListDTO(String language);

    /**
     * 获取学校统计信息
     *
     * @return SchoolStatisticsDTO 学校统计信息
     * @see com.dnndo.system.domain.dto.SchoolStatisticsDTO
     */
    SchoolStatisticsDTO getSchoolStatistics();

    /**
     * 查询学校官方校徽信息
     *
     * @param dto 查询条件
     * @return List<SchoolOfficialDTO> 学校官方校徽列表
     * @see com.dnndo.system.domain.dto.SchoolOfficialDTO
     */
    List<SchoolOfficialDTO> schoolBadgeOfficial(SchoolOfficialDTO dto);

    /**
     * 获取学校信息（中文版）
     *
     * @param dto 查询条件
     * @return ApiSchoolZhVO 中文版学校信息
     * @see com.dnndo.system.domain.dto.ApiSchoolDTO
     * @see com.dnndo.system.domain.vo.ApiSchoolZhVO
     */
    ApiSchoolZhVO getSchoolInfoZh(ApiSchoolDTO dto);
    
    /**
     * 获取学校信息（英文版）
     *
     * @param dto 查询条件
     * @return ApiSchoolEnVO 英文版学校信息
     * @see com.dnndo.system.domain.dto.ApiSchoolDTO
     * @see com.dnndo.system.domain.vo.ApiSchoolEnVO
     */
    ApiSchoolEnVO getSchoolInfoEn(ApiSchoolDTO dto);

    /**
     * 获取校徽总数
     *
     * @param dto 查询条件
     * @return int 校徽总数
     * @see com.dnndo.system.domain.dto.SchoolOfficialDTO
     */
    int countSchoolBadgeOfficial(SchoolOfficialDTO dto);
}
